Problem

When AWS S3 permissions are missing (e.g., s3:HeadBucket), Preevy fails with an unhelpful "403: UnknownError" message that provides no indication the problem is S3-related or which specific AWS permission is missing. This makes it difficult for users to diagnose and resolve permission issues.

Solution

Enhanced error handling in the S3 filesystem implementation (packages/driver-lightsail/src/fs/index.ts) to provide clear, actionable error messages that:

1. Identify S3 as the source - Users immediately know the error is S3-related
2. Specify the failed operation - Shows exactly which S3 API call failed (HeadBucket, GetObject, PutObject, DeleteObject)
3. Provide location context - Includes the S3 bucket/key for debugging
4. Give actionable guidance - For 403 errors, specifically mentions checking AWS permissions
5. Preserve debug info - Maintains original error details for technical troubleshooting

Before vs After

Before (opaque):

403: UnknownError

After (clear and actionable):

Access denied when trying to check bucket permissions (HeadBucket) on Preevy profile S3 bucket. Please check your AWS permissions for the check bucket permissions (HeadBucket) operation.
Location: s3://preevy-123456789-myprofile
S3 Operation: check bucket permissions (HeadBucket)
HTTP Status: 403
AWS Error: AccessDenied
Details: Access Denied

Implementation

• Added createS3Error() helper function to wrap S3 operations with contextual error messages
• Enhanced ensureBucketExists() to provide specific context for HeadBucket/CreateBucket failures
• Improved error handling in all S3 filesystem operations (read, write, delete)
• Preserved original error information for debugging while making messages user-friendly

Testing

• All builds and lints pass successfully
• Changes are minimal and surgical, affecting only error messaging
• Maintains backward compatibility and preserves all original error information
• No functional behavior changes, only improved error reporting

This fix directly addresses the issue where users with missing S3 permissions (like the reported s3:HeadBucket case) now get clear guidance on which AWS permissions need to be configured.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.